QuickTime Music Architecture
| Previous | Chapter Contents | Chapter Top | Next |
This section describes the functions the tune player provides for setting, queueing, and manipulating music sequences. It also describes tune player utility functions.
The TuneSetHeader function prepares the tune player to accept subsequent music event sequences by defining one or more parts to be used by sequence Note events.
pascal ComponentResult TuneSetHeader(
TunePlayer tp,
unsigned long *header);
The TuneSetHeader function is the first QuickTime music architecture call to play a music sequence. The header parameter points to one or more initialized General events and atomic instruments. The event list pointed to by the header parameter must conclude with a marker event of subtype end.
Only one call to TuneSetHeader is required. Each TuneSetHeader call resets the tune player.
The TuneSetHeaderWithSize function is like the TuneSetHeader function in that it prepares the tune player to accept subsequent music event sequences by defining one or more parts to be used by sequence Note events. But unlike the TuneSetHeader function, TuneSetHeaderWithSize allows you to specify the header length in bytes. This prevents the call from parsing off the end if the music event sequence is missing an end marker.
extern pascal ComponentResult TuneSetHeaderWithSize(
TunePlayer tp,
unsigned long *header,
unsigned long size);
You use the TuneSetNoteChannels function to assign note channels to a tune player.
extern pascal ComponentResult TuneSetNoteChannels(
TunePlayer tp,
unsigned long count,
NoteChannel *noteChannelList,
TunePlayCallBackUPP playCallBackProc,
long refCon);
When you call TuneSetNoteChannels, any note channels that were previously assigned to the tune player are no longer used and are disposed of.
The parts for the note channels you assign are numbered from 1 to the value of the count parameter.
The playCallBackProc and refCon parameters let you to use the tune player as a general purpose timer/sequencer. The function in your software pointed to by the playCallBackProc parameter is called for each event whose part number is greater than the value of the count parameter. Events whose part numbers are less than or equal to the value of the count parameter are passed to the note channel rather than the callback procedure.
The playCallBackProc parameter must point to a function with the following prototype:
typedef pascal void (*TunePlayCallBackProcPtr)(
unsigned long *event,
long seed,
long refCon);
The event parameter is a pointer to a QuickTime music event structure in the sequence data. The seed parameter is a 32-bit value that is guaranteed to be different for each call to the callback routine (unless 2^32 calls are made, after which the values repeat), with one exception: the value passed at the beginning of a note is also passed at the end of the note's duration, together with a note structure or an extended note in which the velocity bits are set to 0 . The refCon parameter is the reference constant that is passed to the TuneSetNoteChannels function.
The TuneQueue function places a sequence of music events into a queue to be played.
pascal ComponentResult TuneQueue(
TunePlayer tp,
unsigned long *tune,
Fixed tuneRate,
unsigned long tuneStartPosition,
unsigned long tuneStopPosition,
unsigned long queueFlags,
TuneCallBackUPP callBackProc,
long refCon);
The tuneStartPosition and tuneStopPosition parameters specify, in time units numbered from zero for the beginning of the sequence, which part of the queued sequence to play. To play all of it, pass 0 and 0xFFFFFFFF, respectively.
If there is a sequence currently playing, the newly queued sequence begins as soon as the active sequence ends unless the queueFlags parameter is kTuneStartNow , in which case the currently playing sequence is immediately terminated and the new one started.
The TuneStop function stops a currently playing sequence.
pascal ComponentResult TuneStop(
TunePlayer tp,
long stopFlags);
The TuneGetVolume function returns the volume associated with the entire sequence.
pascal ComponentResult TuneGetVolume(
TunePlayer tp);
The TuneSetVolume function sets the volume for the entire sequence.
pascal ComponentResult TuneSetVolume(
TunePlayer tp,
Fixed volume);
The TuneSetSoundLocalization function passes sound localization data to a tune player.
extern pascal ComponentResult TuneSetSoundLocalization(
TunePlayer tp,
Handle data);
The TuneGetTimeBase function returns the time base of the tune player.
pascal ComponentResult TuneGetTimeBase(
TunePlayer tp,
TimeBase *tb);
The TuneGetTimeBase function returns, in the tb parameter, the time base used to control the sequence timing. The sequence can be controlled in several ways through its time base. The rate of playback can be changed, or the TimeBase object can be slaved to a clock or time base different than real time.
The TuneGetTimeScale function returns the current time scale, in units-per-second, for the specified tune player instance.
pascal ComponentResult TuneGetTimeScale(
TunePlayer tp,
TimeScale *scale);
The TuneSetTimeScale function sets the time scale used by the specified tune player instance.
pascal ComponentResult TuneSetTimeScale(
TunePlayer tp,
TimeScale scale);
You use the TuneGetPartMix function to get volume, balance, and mixing settings for a specified part of a tune.
pascal ComponentResult TuneGetPartMix (
TunePlayer tp,
unsigned long partNumber,
long *volumeOut,
long *balanceOut,
long *mixFlagsOut);
You use the TuneGetPartMix function to set volume, balance, and mixing settings for a specified part of a tune.
pascal ComponentResult TuneSetPartMix (
TunePlayer tp,
unsigned long partNumber,
long *volume,
long *balance,
long *mixFlags);
You can use the TuneInstant function to play the particular sequence events active at a specified position.
pascal ComponentResult TuneInstant(
TunePlayer tp,
unsigned long *tune,
unsigned long tunePosition);
The TunePreroll function prepares for playing tune player sequence data by attempting to reserve note channels for each part in the sequence.
pascal ComponentResult TunePreroll (TunePlayer tp);
The TuneUnroll function releases any note channel resources that may have been locked down by previous calls to TunePreroll for this tune player.
pascal ComponentResult TuneUnroll (TunePlayer tp);
You can use the TuneGetIndexedNoteChannel function to determine how many parts the tune is playing and which instrument is assigned to those parts.
pascal ComponentResult TuneGetIndexedNoteChannel(
TunePlayer tp,
long i,
NoteChannel *nc);
The tune player allocates note channels that best satisfy the requested instrument in the tune header. The application can use this call to determine which instrument was actually used for each note channel. The TuneGetIndexedNoteChannel function takes the tune player in the tp parameter and returns the number of parts (1...n) allocated to the tune player. You can then pass the function a part index and it returns, in the nc parameter, the note channel allocated for that part.
The TuneGetStatus function returns an initialized structure describing the state of the tune player instance.
pascal ComponentResult TuneGetStatus(
TunePlayer tp,
TuneStatus *status);
The TuneSetPartTranspose function modifies the pitch and volume of every note of a tune.
extern pascal ComponentResult TuneSetPartTranspose(
TunePlayer tp,
unsigned long part,
long transpose,
long velocityShift);
The TuneGetNoteAllocator function returns the instance of the note allocator that the tune player is using.
extern pascal NoteAllocator TuneGetNoteAllocator (TunePlayer tp);
The TuneSetSofter function adjusts the volume a tune is played at to the softer volume produced by QuickTime 2.1. Files imported with QuickTime 2.1 automatically played softer. Files imported with QuickTime 2.5 or later play at the new, louder volume.
extern pascal ComponentResult TuneSetSofter(
TunePlayer tp,
long softer);
Use the TuneSetBalance function to modify the pan controller setting for a tune player.
extern pascal ComponentResult TuneSetBalance(
TunePlayer tp,
long balance);
Call the TuneTask function periodically to allow a tune player to perform tasks it must perform at foreground task time.
extern pascal ComponentResult TuneTask (TunePlayer tp);
| Previous | Chapter Contents | Chapter Top | Next |